Player Management

HCGE supports up to 2 simultaneous Player Characters, which correspond with the two available display screens. While normal Game Objects may also be used to achieve the effect of a playable character if desired, the Player Characters use a more sophisticated system for movement and collision management. The Player Management system is composed of the following 7 parts:

- Character Def
- Character Common Functions
- Player Variables
- Movement Modes
- Path Modes
- Player Movement Object
- Player Draw Object
- Player "Fetching" and Pointers


- Character Def
The Character Def is a setup file used to define properties of the player character such as his art, his Movement Modes, his animations, and his own unique script functions. The Game Def contains a list of these files to load for each player character type

- Character Common Functions
Aside from the Character Def file, there is an additional file that contains only script functions, which serves as a list of functions that all player characters can use. This is in addition to the Character-Specific Functions listed in each Character def, so that functions that more than one player character can use do not have to be stored more than once. The Game Def contains an entry that should be set to the name of this file

Although it's not usually necessary, if a Script Command that references this Function List must be used to access a Character-Specific Function, that Function may be referenced by calculating its "Full List ID". This ID is calculated as if all Player-Specific Functions were set in a single list in the order in which the Character Def files were loaded, immediately following the Common Functions. For example, if there are 5 Common Functions, and the Command must reference Character 0's Function 3, then its Full List ID (5+3) would be 8. If there are 7 Common Functions, and Character 0 has 5 Functions, the Full List ID of Character 1's Function 2 (7+5+2) would be 14.

- Player Variables
The Player Variables are settings that are read and modified during gameplay by HCGE and script functions to determine or control where the player is and what he is doing

- Movement Modes
Movement Modes are set up within the Character Def, and are used to create differing player states, in which the player reacts differently to input and the environment. script functions may change the Movement mode at any time by changing the Player Variable Player_Movement_Mode to create such effects as causing a player to react to taking damage, or change the player's action in response to certain input. Movement Modes are separate from Path Modes, and changing both independantly can cause different effects. They are made up of the following parts:

-Movement Function
The Movement Function is a character script function used during the Movement Phase. Because HCGE's Path Mode movement is generic, this Function is responsible for controlling player velocities, their reactions to level collision, and any other game-specific player behavior
-Update Function
The Update Function is a character script function used during the Update Phase. This Function is responsible for controlling which Animation the character is playing at any given time. Using different Update Functions for each Movement Mode and Setting player animation based on conditional tests of Player Variables can achieve visual effects that the player is performing different actions in relation to his state and environment. This Function can also be used for manual Viewport control, or to change the Automatic Viewport Settings, as it is called after movement, and before animation and viewport control
-Key Events
Key Events are character script functions activated by keypresses; This controls the player's reaction to input. Each Movement Mode can have multiple Key Events, such as the a primary mode having events for "move left", "move right", and "jump". All keys designated for one individual Key Event must be pressed (or held, depending on the defined condition) at the same time to activate the event. This makes up the player's Input Phase, and though this is the primary method for using input to control the character, any other script function may also test for input states during its own processing

- Path Modes
Path Modes are the hard-coded movement modes which HCGE uses to move the player based on his Velocities and test for collision against objects and level tile planes. These modes are the first part of the Movement Phase, and occur before the scripted Movement Mode handling, which are responsible for all other player control functionality.

The velocities by which the player is moved are "fixed-point" values, meaning that they are whole numbers that describe whole and partial pixel movement counts. This value allows for 256 units of partial movement before the player is moved one unit across the screen, which means that the number of whole pixels that the player will move is velocity/256, or velocity>>8. At the beginning of player movement, the current X and Y Velocities are added to the Count variables, which are used as counters while the player moves one whole pixel unit through the level at a time. After each unit of movement, the player tests for collisions with the current solid level plane, runs the scripted collision functions for each active game object, and removes 256 (one whole pixel unit) from the counter, until there are less than 256 units of velocity left, which are left in the counter until the next frame. This method allows for smooth acceleration when the player's velocity is increased by units less than 256 (one pixel), since partial units of velocity are preserved between game frames, and collision testing for every whole unit of motion allows for finer collision testing, allowing the player to react to collision at the exact moment that it happens (during player movement, though not during object movement)

The player's velocities are made up of the X and Y "component velocities", and the "Path"/Vector velocity. The "Path Velocity" is the speed at which the player is moving along a path, or in freespace. When the player is flagged for "vector movement", the Path Angle is used to break the Path Velocity into the component X and Y velocities, which are used as described above. When not using vectored movement, or when in freespace, the full Path Velocity value is used as the player's speed based on the current Path Mode in the following way: 
	Floor:		X =  Path, y = y
	Ceiling:	X = -Path, y = y
	LWall:		Y =  Path, x = x
	RWall:		Y = -Path, x = x
	Other:		x =     x, y = y
There are 9 valid Path Mode settings that control in what direction "path" collisions are processed:

0 - _PPM_Floor
This mode tests for level collision below the player. If flagged to do so, crossing 45-degree angles while on this path will transition to either the Left or Right wall mode. Level Collision is read using the MainBound box in normal orientation

1 - _PPM_Right
This mode tests for level collision to the right of the player. If flagged to do so, crossing 45-degree angles while on this path will transition to either the Floor or Ceiling wall mode. If the player is flagged to use rotated MainBounds, collision is read with the box rotated 90-degrees clockwise

2 - _PPM_Ceiling
This mode tests for level collision above the player. If flagged to do so, crossing 45-degree angles while on this path will transition to either the Left or Right wall mode. If the player is flagged to use rotated MainBounds, collision is read with the box rotated 180-degrees

3 - _PPM_Left
This mode tests for level collision to the left of the player. If flagged to do so, crossing 45-degree angles while on this path will transition to either the Floor or Ceiling wall mode. If the player is flagged to use rotated MainBounds, collision is read with the box rotated 90-degrees counterclockwise

4 - (No Collision)
5 - (No Collision)
6 - (No Collision)
7 - (No Collision)
These modes do not test for collision with the level or with Objects, and "Path Velocity" has no effect

8 - _PPM_Debug
This mode functions the same as the "No Collision" modes, except that the Player's image is replaced by an image representing the Debug Object currently selected by his Player_DebugNum variable, based on that Object Type's Debug Draw Function.

The primary function of this mode is to make the initial placement of Objects into a Level. This can be accomplished by creating a special Movement Mode for the Player Character that makes use of this Path Mode and contains Key Events for triggering the _Debug_PlaceObject Script Command, as well as manipulating the Player_DebugNum variable. Other considerations could be the manipulation of other custom variables for use by the Object's Scripted Object Debug Placement Function to further control the way its spawned, and possibly calling the _SaveObjects Script Command.

Each of the first four Path Modes are made up of two parts:

- Path Tracer
When a player is connected to a "Path" (A level plane, a Solid Tiled Object or a Solid Object), he is moved by the Path Tracer. The Path Tracer moves the player along the path based on his Path Velocity, as described above. The player is moved along the path at the speed designated by the component velocity on the axis that corresponds with his current path mode. The player is moved one pixel at a time along the path as described above, ignoring velocity on the other axis, as it is only representative of the rise or fall of the path itself, so the player is moved up or down according to the shape of the solid path, as long as the difference in height is equal to or less than the Slope Tolerance settings. If a rise is greater than the tolerance, the path ahead is regarded as a wall, and the player is stopped. If a drop is greater than the tolerance, it is regarded as the end of the path, at which point the player "disconnects" from the path and enters Freespace, unless object collisions have also set the player as standing on a solid object. This mode only affects the player if he is flagged to follow paths

- Freespace Movement
When a player is not connected to a "Path", he is considered to be in "Freespace". Path Velocity is still used as described above, but both component velocities are used to move the player along a diagonal line. The player is moved one unit at a time along the diagonal line, testing for object and level collisions along the way. When the player strikes level solidity or a solid object in the direction of his current Path Mode, he "connects" to the path and enters "Path Tracer" mode, but only if he is flagged to follow paths. While still in Freespace, if the player is moving "forward" or "backward" relative to his Path Mode without moving "up", and strikes solidity from the "ceiling", the player is moved down by the difference between the "upper" portion of his MainBounds, and the lowest point of the "ceiling"'s solidity if the difference is less than or equal the Slope Tolerance settings. If the difference is greater, the solidity is treated as a "wall", and the player's movement in that direction is stopped. To prevent any level collision from occurring at all, the player's Solid Plane can be set equal to the ID of a tile plane that has no solidity

- Player Movement Object
The Player Movement Object is a built-in game object that causes the player to process his movement and script functions. This object must be spawned for each player that is meant to function in each level. This object processes in three phases, which occur in the following order:

- Movement Phase
The Movement Phase is responsible for a player's movement and interaction with his environment. The Movement Phase is actually composed of two parts:

- Hard-coded Movement
Hard-coded movement consists only of HCGE moving the player according to his Path Mode. Any other physics are left to the Scripted Movement, or the Object Collision Functions that may be triggered during this period. This movement occurs before any Game Object is moved during the current game frame, but only if a Player Movement Object has been spawned and assigned to this player

- Scripted Movement
Scripted Movement is the second step in player movement, and is processed when the Player Movement Object is reached during Game Object Processing. When this happens in relation to the processing of other Game Objects is determined by the Priority assigned to each object. At this time, HCGE calls the Script Function designated as the "Movement Function" by the player's current Movement Mode. This function is responsible for assigning game-specific physics to the player, such as gravity, acceleration, etc. This function is also responsible managing individual player timers, and the player's state relative to his environment. Without this function, the Hard-coded movement would simply move the player across the level at a constant velocity, if he were given an initial velocity to begin with

This is also the point at which any "Sentry Function" would be running. First, the designated "Movement Function" is run, and then, any function that was called during the "Movement Function" or the player's "Init Function" that was set to break and/or loop will run in the order in which they were called. These "Sentry Functions" can perform tasks that are common to all Movement Modes that do not share a common "Movement Function", or any other repeating action that may be required by the player at this point during processing. These Functions may be managed during Player Movement or Input by using the standard Function Call/Run Script Commands or those based on Player Variables or Player Function Listing, or at any other time using the external Player Movement Function Control Script Commands.

- Input Phase
Immediately after the Movement Phase, the Input Phase processes the Key Events designated by the player's current Movement Mode. This phase is largely responsible for taking input and causing the Player Character to react, but other functions may also test for keypresses at any time whenever necessary

- Update Phase
The Update Phase, the final part of Player Movement, is responsible for processing the Player Character's Animations, and updating the player's Viewport. This phase is made up of 3 parts that are run in the following order:

- Scripted Update Function
The Update Phase begins by calling the "Update Function" listed for the player's current Movement Mode. This function is responsible for managing the player's current Animation, to create the visual effect that the player is reacting differently to changes in the environment or his current state. This function may also be used to change automatic viewport settings if the player is flagged to use them, or if not, the Viewport may be managed manually at this time. This is done by directly manipulating the vp?r[?] Game Registers

- Animation
After the Scripted Update Function is run, HCGE processes the player's currently-set Animation Function, which is responsible for setting the player's display frame and the time delay before the next. Because the Animations are normal Script Functions, they may also perform other tasks such as playing sounds, offsetting the player's position, etc. as necessary

- Automatic Viewport Update
The Update Phase is concluded with the processing of the Automatic Viewport Update, if it is enabled. If so, the settings in the currently-set player character's Character Def are used to determine how far away from the top-left corner of the screen the player must be for the Viewport to be moved in any of the four directions, and how fast the Viewport is allowed to move to keep up. This behavior is applied to the player's own Viewport variables, which are then copied to the vp?r[?] Game Registers, offset by the player's panning variables, and then clipped to the current Level Boundaries

- Player Draw Object
The Player Draw Object is a built-in game object that must be spawned and assigned to a Player Character before that Player Character will become visible. When this object is reached during Game Object Processing, the last display frame set by the player's currently-running Animation will be drawn to the screen. When this happens in relation to the drawing of other Game Objects is determined by the Priority assigned to each object

- Player "Fetching" and Pointers
Player "Fetching" is the method by which Players are set as the "Source" and/or "Destination" for Script Commands that manipulate Player Variables, or any other aspect of a Player. Because there are at most two Sources and one Destination used by any Script Command, there are three "References" that any Player can be "Fetched" into. Using the mathematical add operation as an example, the general rule is:

    Z = X + Y

    Where:

    • X is Reference 0 - The first Source operand
    • Y is Reference 1 - The second Source operand
    • Z is Reference 2 - The Destination operand

This is also true for operations with only one Source operand, and for non-mathematical operations. Any Player that is being manipulated in any way is considered to be the "Destination", while any Player or Object that provides information for the manipulation of the Destination is considered to be a "Source". If a Command uses only one Source, The one Source Parameter is "Reference 0". If there are two Sources that are both Players, then the first Source Parameter is "Reference 0", and the second is "Reference 1". Since Players are considered distinct from other Objects, they have their own set of References; this means that if there are two Sources, one Object and one Player, the first Source Parameter is "Reference 0" in terms of Objects, and the second Source Parameter is "Reference 0" in terms of Players.

A single Player may be "Fetched" to more than one "Reference" if it must serve as both Sources, one Source and the Destination, or both Sources and the Destination.

Pointers to Players can be obtained by use of the Func_???_Equ_Pointer_???_Chr Script Commands and stored in any Player Variable, Game Variable, or Object Variable for later retrieval by "Fetch". This method of Player referencing can allow any part of the game to keep up with any one Player for any reason.